클로드 코드 완벽 가이드 — 14장 깃허브 워크플로 사용하기 딥다이브 학습 노트

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호) | 참고: https://github.com/codefactory-co

14장에서 다루는 내용

• 깃허브 이슈 이해하기 — 이슈의 구성 요소(제목, 본문, 담당자, 레이블, 마일스톤, 프로젝트, 연결된 PR)를 이해하고 프로젝트 관리에 활용
• 깃허브 CLI 설치하기 — gh CLI를 설치하고 깃허브 계정과 SSH 인증으로 연동
• 레이블 생성하기 — 개발 영역, 복잡도, 작업 유형별 레이블을 클로드 코드로 일괄 생성
• 이슈 생성하기 — 커스텀 슬래시 커맨드(/decompose-issue)로 작업을 세분화하고 이슈 템플릿에 맞게 이슈를 자동 생성
• 이슈 작업하기 — 커스텀 슬래시 커맨드(/resolve-issue)로 이슈를 체계적으로 해결 (8단계 워크플로)
• 병렬로 이슈 작업하기 — Git Worktree와 셸 스크립트를 활용하여 여러 이슈를 동시에 독립적으로 해결

전체 흐름도

[깃허브 이슈 이해하기]        [깃허브 CLI 설치하기]
    |                              |
    v                              v
+------------------------+   +---------------------------+
| 이슈 구성 요소          |   | gh CLI 설치               |
| - 제목/본문             |   | - winget/choco/brew       |
| - 담당자/레이블         |   | gh auth login             |
| - 마일스톤/프로젝트     |   | - SSH 프로토콜 선택       |
| - 연결된 풀 리퀘스트    |   | - 웹 브라우저 인증        |
+------------------------+   +---------------------------+
           |                          |
           v                          v
+------------------------------------------------------+
| 레이블 생성하기                                        |
| gh label create "영역:프론트엔드" --color "D4F4FA"      |
| gh label create "복잡도:복잡" --color "F9D0C4"          |
| gh label create "종류:기능" --color "F4B6C2"            |
+------------------------------------------------------+
           |
           v
+------------------------------------------------------+
| 이슈 생성하기 (/decompose-issue 커스텀 커맨드)          |
| 1. 작업 분석 → 2. 작업 분해 → 3. 의존성 분석            |
| 4. 분해된 이슈 출력 → 5. 깃허브에 이슈 생성              |
| (이슈 템플릿: 제목/레이블/설명/작업유형/완료조건/         |
|  구현 참고사항/의존성)                                  |
+------------------------------------------------------+
           |
           v
+------------------------------------------------------+
| 이슈 작업하기 (/resolve-issue 커스텀 커맨드)             |
| 1. 이슈 불러오기 → 2. 브랜치 세팅                       |
| 3. 코드베이스 분석 → 4. 이슈 해결 계획 세우기             |
| 5. 이슈 해결하기 → 6. 테스트 작성하기                     |
| 7. 검증하기 → 8. 풀 리퀘스트 생성                        |
+------------------------------------------------------+
           |
           v
+------------------------------------------------------+
| 병렬로 이슈 작업하기                                    |
| Git Worktree + create-worktree.sh 셸 스크립트           |
| 워크트리별 독립 브랜치 → 병렬 이슈 해결                   |
| → 메인 브랜치로 병합                                    |
+------------------------------------------------------+

선수 지식 체크리스트

• [ ] Git 기본 사용법 (commit, branch, merge)
• [ ] 깃허브 계정 및 리포지토리 사용 경험
• [ ] 클로드 코드 커스텀 슬래시 커맨드 작성법 (5장)
• [ ] 서브에이전트 개념 (7장)
• [ ] Git Worktree 기본 개념 (13장)

핵심 키워드

14-1 깃허브 이슈 이해하기

한 줄 요약

프로젝트의 개선점, 버그, 아이디어를 깃허브 이슈로 중앙 관리하며, 이슈는 제목/본문/담당자/레이블/마일스톤/프로젝트/연결된 PR 7가지 요소로 구성된다.

쉬운 설명 (비유)

깃허브 이슈 = 회사의 "업무 요청서"

여러분이 식당을 운영한다고 생각해 보세요:
- "새 메뉴 추가해야 해" → 새로운 기능 (기능 이슈)
- "에어컨이 고장났어" → 버그 (버그 이슈)
- "디저트 코너를 만들면 어떨까?" → 아이디어 (제안 이슈)

이런 요청서들을 한 곳에 모아두고 관리하는 게 깃허브 이슈!

깃허브 이슈의 구성 요소

왜 깃허브 이슈로 관리해야 하는가?

❌ 이슈 없이 작업하는 경우:
클로드 코드 → 너무 빠르게 진행 → 문서만으로 관리
→ 팀원끼리 공유 어려움 → 협업 장애 발생

✅ 깃허브 이슈로 관리하는 경우:
작업을 이슈로 등록 → 레이블/담당자 지정 → 진행 상황 추적
→ 팀 전체가 한눈에 파악 → 협업 원활

핵심 체크포인트

• 깃허브 이슈는 프로젝트의 모든 논의와 작업 관리를 중앙화하는 도구
• 이슈 7가지 구성 요소(제목, 본문, 담당자, 레이블, 마일스톤, 프로젝트, 연결된 PR)를 이해
• 버그 리포트는 재현 방법, 예상 결과, 실제 결과를 명확히 기술
• 풀 리퀘스트와 이슈를 연결하면 PR 병합 시 이슈 자동 종료 가능

14-2 깃허브 CLI 설치하기

한 줄 요약

클로드 코드와 깃허브를 연동하기 위해 gh CLI를 설치하고, SSH 프로토콜과 웹 브라우저 인증으로 계정을 연결한다.

쉬운 설명 (비유)

gh CLI = 깃허브의 "리모컨"

웹사이트에 매번 접속하지 않고도
터미널에서 바로 이슈 생성, PR 올리기, 댓글 달기가 가능!

마치 TV 앞까지 안 가도 리모컨으로 채널 돌리는 것과 같다.

깃허브 연동 방식 2가지

gh CLI 설치 방법

# Windows (WinGet)
winget install --id GitHub.cli

# Windows (Chocolatey)
choco install gh

# macOS (Homebrew)
brew install gh

# 설치 확인
gh --version
# gh version 2.74.2 (2025-06-17)

gh auth login 인증 절차 (9단계)

01. gh auth login 실행
02. gh --version으로 설치 확인
03. Where do you use GitHub? → GitHub.com 선택
04. What is your preferred protocol? → SSH 선택
05. Upload your SSH public key → 기존 pub키 선택
06. Title for your SSH key → Enter (기본값)
07. How would you like to authenticate? → Login with a web browser
08. Press Enter to open... → Enter 누르기
09. 브라우저에서 깃허브 계정 선택 → 연동 완료

실무 예제: gh CLI 활용

# 이슈 목록 보기
gh issue list

# 이슈 생성
gh issue create --title "버그 수정" --body "상세 내용"

# PR 생성
gh pr create --title "기능 추가" --body "설명"

# 이슈 상세 보기
gh issue view 200 --json title,body,labels,state

핵심 체크포인트

• 깃허브 연동은 MCP보다 gh CLI가 공식 추천 방식
• SSH 프로토콜을 선택하여 보안성 높은 인증 구성
• gh auth login으로 9단계 인증 절차 완료
• 클로드 코드는 gh CLI가 설치되면 자동으로 깃허브 API를 활용

14-3 레이블 생성하기

한 줄 요약

깃허브 워크플로의 효율성을 위해 개발 영역, 복잡도, 작업 유형, 도메인 4가지 카테고리의 레이블을 gh CLI로 일괄 생성한다.

쉬운 설명 (비유)

레이블 = 서류의 "색깔 태그"

파일철에 빨간 태그(긴급), 파란 태그(일반), 노란 태그(참고)를
붙여서 한눈에 구분하는 것과 같다.

깃허브 레이블도 이슈에 태그를 붙여서:
- 어떤 영역인지? (프론트엔드/백엔드)
- 얼마나 어려운지? (쉬움/보통/복잡)
- 어떤 종류인지? (기능/버그/테스트)
한눈에 파악할 수 있게 해준다.

레이블 카테고리 4가지

레이블 일괄 생성 명령어

# 개발 영역
gh label create "영역:프론트엔드" --description "프론트엔드 관련 작업" --color "D4F4FA"
gh label create "영역:백엔드" --description "백엔드 관련 작업" --color "E9DEFA"
gh label create "영역:DevOps" --description "배포 및 인프라 작업" --color "FBE6C6"

# 복잡도
gh label create "복잡도:복잡" --description "상당한 노력이 필요한 복잡한 작업" --color "F9D0C4"
gh label create "복잡도:보통" --description "일반적인 수준의 작업" --color "FEF2C0"
gh label create "복잡도:쉬움" --description "간단하고 빠르게 처리할 수 있는 작업" --color "B4E1D2"

# 작업 유형
gh label create "종류:다큐멘테이션" --description "문서 작성 또는 수정" --color "C5DEF5"
gh label create "종류:기능" --description "새로운 기능 개발" --color "F4B6C2"
gh label create "종류:테스트" --description "테스트 코드 작성 또는 리팩터링" --color "D4C5F9"
gh label create "종류:버그" --description "버그 수정" --color "f29513"
gh label create "종류:리팩터링" --description "코드 품질 개선" --color "a2eeef"

레이블의 실무 활용 장점

1. 에이전트에게 병렬로 작업을 분배할 때 서로 겹치지 않는지 확인
2. 클로드 모델 선택 기준 — 복잡도 레이블로 판단
   - 복잡도:복잡 → 클로드 Opus
   - 복잡도:쉬움 → 클로드 Sonnet
3. 이슈 필터링 — 원하는 이슈만 빠르게 찾기

핵심 체크포인트

• 레이블은 4가지 카테고리(영역, 복잡도, 유형, 도메인)로 체계적으로 구성
• 클로드 코드에게 프롬프트를 주면 gh label create 명령어를 자동 생성
• 복잡도 레이블은 AI 모델 선택 기준으로도 활용
• 레이블 형태는 팀/프로젝트 상황에 맞게 자유롭게 분류 가능

14-4 이슈 생성하기

한 줄 요약

커스텀 슬래시 커맨드(/decompose-issue)를 만들어 큰 작업을 작은 이슈들로 세분화하고, 이슈 템플릿에 맞는 구조화된 이슈를 깃허브에 자동 생성한다.

쉬운 설명 (비유)

이슈 세분화 = 큰 피자를 조각으로 나누기

"사용자 프로필 페이지를 만들어 줘"라는 큰 작업 (피자 한 판)을
→ "프로필 이미지 변경" (1조각)
→ "비밀번호 변경" (1조각)
→ "소개 변경" (1조각)
→ "로그아웃" (1조각)
으로 나누면 한 번에 하나씩 먹을 수 있다!

각 조각이 하나의 깃허브 이슈가 되는 것이다.

/decompose-issue 커스텀 커맨드 구조

파일 위치: .claude/commands/decompose-issue.md

# 작업 세분화하기
너는 이제부터 작업을 세분화하는 전략 전문가야.
아규먼트로 세분화해야 하는 작업을 입력받고
그 작업을 독립적인 여러 개의 이슈로 분해하는 작업을 해줘.

## 작업 순서
1. 작업 분석: 핵심 요구사항과 목표를 이해하기
2. 작업 분해: 더 작고 관리하기 쉬운 하위 작업/이슈로 나누기
3. 의존성 분석: 다른 작업이 선행돼야 하는 의존성 파악하기
4. 분해된 이슈 출력: 분해된 이슈들을 출력하기
5. 깃허브에 이슈를 생성할지 묻기: 사용자가 결정하도록 요청

이슈 템플릿 구조

title: [종류] 명확하고 실행 가능한 제목
labels:
- 종류:기능|종류:버그|종류:리팩터링|종류:테스트|종류:다큐멘테이션
- 영역:프론트엔드|영역:백엔드|영역:DevOps
- 복잡도:쉬움|복잡도:보통|복잡도:복잡
---
## 설명
[무엇을 해야 하고 왜 해야 하는지]
## 작업 유형
- [ ] 백엔드 / 프론트엔드 / 풀스택 / 기타
## 완료 조건
- [ ] 특정 요구사항 1, 2...
- [ ] 테스트 통과 / 린팅 통과 / 문서 업데이트
## 구현 참고사항
### 수정할 파일 / 따를 패턴 / 기술적 고려사항
## 의존성
- [ ] 이슈 #[번호]가 먼저 완료되어야 함

실무 예제: 사용자 프로필 페이지 이슈 분해

프롬프트: /decompose-issue 사용자 프로필 페이지를 완성하려고 해.
         프로필 이미지 변경, 비밀번호 변경, 소개 변경, 로그아웃을
         할 수 있도록 구성해 줘.

클로드 코드의 분해 결과:
→ 이슈 #1: 프로필 이미지 변경
→ 이슈 #2: 비밀번호 변경 기능 구현
→ 이슈 #3: 소개 변경
→ 이슈 #4: 로그아웃

우선순위 추천:
→ 이슈 #1과 #3을 병렬로 진행 (독립적)
→ 이슈 #1 완료 후 #2와 #4를 진행

이슈 #2 비밀번호 변경 기능 구현 — 상세 예시

title: [기능] 비밀번호 변경 기능 구현
labels: 종류:기능, 영역:풀스택, 복잡도:복잡

## 설명
사용자가 현재 비밀번호를 확인하고 새 비밀번호로 변경할 수 있는 기능을 구현합니다.

## 완료 조건
- 비밀번호 변경 폼 컴포넌트 생성
- 현재 비밀번호 검증
- 새 비밀번호 강도 검증
- 서버 액션 구현
- Supabase 비밀번호 업데이트 API 연동
- 성공/실패 피드백
- 테스트 통과 / 린팅 통과

## 구현 참고사항
### 수정할 파일
- components/profile/password-change-form.tsx — 새 컴포넌트
- app/actions/auth/change-password.ts — 새 서버 액션
- lib/validations/auth.ts — 비밀번호 검증 스키마 추가
- app/profile/edit/page.tsx — 비밀번호 변경 섹션 추가

### 따를 패턴
- 참조: @/app/actions/auth/login.ts
- TanStack Form 사용
- Zod 검증 스키마

### 기술적 고려사항
- Supabase Auth API 사용
- 비밀번호 강도 검증 (최소 8자, 대소문자, 숫자, 특수문자)
- 보안을 위한 rate limiting 고려

## 의존성
- 이슈 #1이 먼저 완료되어야 함

## 예상 소요 시간
4-8시간

핵심 체크포인트

• /decompose-issue 커맨드는 큰 작업을 클로드 코드에게 자동으로 세분화시킴
• 이슈 템플릿으로 일관된 형식(제목, 레이블, 설명, 완료 조건, 의존성 등)을 강제
• 이슈 단위로 나누는 게 가장 중요 — 작을수록 한 번에 해결 가능
• "생성해달라"고 답하면 클로드 코드가 모든 이슈를 깃허브에 자동 업로드

14-5 이슈 작업하기

한 줄 요약

커스텀 슬래시 커맨드(/resolve-issue)를 만들어 깃허브 이슈를 8단계(이슈 불러오기 → 브랜치 → 코드 분석 → 계획 → 해결 → 테스트 → 검증 → PR 생성) 워크플로로 체계적으로 해결한다.

쉬운 설명 (비유)

이슈 해결 = 의사의 진료 과정

1. 환자 정보 확인 (이슈 불러오기)
2. 진료실 준비 (브랜치 세팅)
3. 검사 (코드베이스 분석)
4. 진단 (해결 계획 세우기)
5. 치료 (이슈 해결하기)
6. 처방 기록 (테스트 작성)
7. 경과 확인 (검증하기)
8. 퇴원 서류 (풀 리퀘스트 생성)

이 과정을 하나의 명령어로 자동화한 것이 /resolve-issue이다!

/resolve-issue 8단계 워크플로

파일 위치: .claude/commands/resolve-issue.md

# 깃허브 이슈 해결하기
너는 지금부터 깃허브 이슈를 해결하는 엘리트 소프트웨어 개발자야.
아규먼트로 깃허브 이슈 고유 숫자를 넘겨주면
이 숫자에 해당되는 Issue를 해결하는 작업을 해줘.

왜 이슈 해결 자체를 여러 서브에이전트로 하지 않는가?

❌ 이슈 해결을 여러 서브에이전트로 나누면:
→ 이미 독립적으로 해결 가능한 작업 단위로 이슈가 나뉘어 있음
→ 다시 세분화하는 건 어색하고 비효율적
→ 서브에이전트가 구현한 코드 합칠 때 충돌 가능성

✅ 이슈 해결은 하나의 서브에이전트로:
→ 구현은 하나의 서브에이전트가 담당
→ 코드베이스 분석, 테스트, 검증은 병렬로 서브에이전트 활용
→ 작업 시간 최소 반 이하로 줄어듦 + 메인에이전트 컨텍스트 절약

실무 사용 예시

# 186번 이슈를 해결할 때
> /resolve-issue 186

클로드 코드가 자동으로:
1. gh issue view 200 --json title,body,labels,state 실행
2. issue-186 브랜치 생성
3. 서브에이전트들이 코드베이스 분석
4. 해결 계획 수립
5. 이슈 해결 (코드 작성)
6. 테스트 작성
7. 테스트/린트/빌드 검증
8. PR 자동 생성
→ 복잡한 프롬프트 없이도 이슈 해결 + 테스트 + 빌드 검증까지 진행

핵심 체크포인트

• /resolve-issue는 이슈 번호 하나만 입력하면 8단계를 자동 실행
• 코드베이스 분석과 검증은 서브에이전트로 병렬 처리하여 속도 향상
• "작업의 완료를 어떻게 확인하고 점검할 것인가?"가 커맨드 설계의 핵심
• 작은 작업 단위로 나누어 순서대로 진행하면 AI도 실제 개발자처럼 동작

14-6 병렬로 이슈 작업하기

한 줄 요약

Git Worktree와 셸 스크립트(create-worktree.sh)를 활용하여 여러 이슈를 독립적인 워크트리에서 동시에 병렬로 해결하고, 완료 후 메인 브랜치로 병합한다.

쉬운 설명 (비유)

병렬 이슈 작업 = 여러 교실에서 동시에 수업하기

학교에 교실이 1개뿐이면 → 한 과목씩 순서대로 수업 (직렬)
교실이 여러 개 있으면 → 수학, 영어, 과학 동시 수업 (병렬)

Git Worktree = 추가 교실을 만드는 것
각 교실(워크트리)에서 별도의 선생님(클로드 코드)이 동시에 수업!

create-worktree.sh 셸 스크립트

#!/bin/bash
if [ $# -eq 0 ]; then
    echo "Error: Worktree 이름을 명시해주세요!"
    return 1
fi
ARGUMENT=$1
WORKTREE_PATH="../${폴더이름}/$ARGUMENT"

# 워크트리 생성 + 디렉터리 이동 + 클로드 실행
if git worktree add "$WORKTREE_PATH"; then
    echo "Worktree 생성 성공: $WORKTREE_PATH"
    cd "$WORKTREE_PATH" || exit 1
    echo "-디렉터리 변경 완료 : $(pwd)"

    # 이슈 번호 추출 후 자동으로 /resolve-issue 실행
    ISSUE_NUMBER=$(echo "$ARGUMENT" | awk -F'-' '{print $NF}')
    if [[ "$ISSUE_NUMBER" =~ ^[0-9]+$ ]]; then
        echo "Running claude command for issue: $ISSUE_NUMBER"
        claude -p "/user:resolve-issue $ISSUE_NUMBER"
    else
        echo "Warning: Could not extract a valid issue number."
    fi
else
    echo "Worktree 생성 실패."
    exit 1
fi

병렬 이슈 작업 전체 흐름

단계 1: 터미널 여러 개 열기

단계 2: 각 터미널에서 워크트리 생성
  터미널 1: ./create-worktree.sh issue-79
  터미널 2: ./create-worktree.sh issue-80
  터미널 3: ./create-worktree.sh issue-81

단계 3: 각 워크트리에서 독립적으로 이슈 해결
  (자동으로 /resolve-issue 실행)

단계 4: 완료된 PR들을 메인 브랜치에서 병합
  git checkout main
  git merge issue-79
  git merge issue-80
  git merge issue-81

매니저로서의 4단계 운영법

1. 제작하고 있는 서비스를 확인하며 필요한 요구사항들을 정리한다.
2. 요구사항을 작은 이슈로 분할하도록 클로드 코드에게 명령하고 이슈들을 깃허브에 올린다.
3. 필요한 만큼 워크트리를 병렬로 생성해서 클로드 코드가 풀 리퀘스트를 올리도록 한다.
4. 깃허브에서 변경 사항들을 모니터링한 후 메인 브랜치로 머지한다.

워크플로 개선 팁

문제 발생 시 해결 방법 (주니어 개발자를 다루듯이):

❌ 이슈가 너무 큰 단위로 나뉘었다
→ ✅ 더 작은 이슈로 세분화

❌ 충돌이 너무 자주 생긴다
→ ✅ 독립적인 이슈로 분할 (의존성 최소화)

❌ 충분히 테스트가 작성되지 않는다
→ ✅ 커스텀 커맨드에 테스트 요구사항 강화

❌ AI가 프로젝트를 잘 다루지 못한다
→ ✅ 작업 플로우 확인, 할당 작업 축소, 부가적인 설명 추가

핵심 체크포인트

• Git Worktree로 여러 브랜치를 동시에 체크아웃하여 병렬 작업
• create-worktree.sh 셸 스크립트로 워크트리 생성 → 클로드 실행 → 이슈 해결 자동화
• 인터렉티브 모드 없이 claude -p 옵션으로 헤드리스 자동 실행 가능
• 워크플로의 문제점은 프롬프트 개선과 이슈 세분화로 해결

연습문제 풀이

Q1: 깃허브 이슈의 구성 요소를 모두 나열하고, 각각의 역할을 설명하세요.

A: (1) 제목과 본문 — 이슈 내용을 명확하게 전달, (2) 담당자 — 이슈를 처리할 사람 지정, (3) 레이블 — 이슈의 종류/우선순위/상태 시각적 구분, (4) 마일스톤 — 특정 목표/버전과 관련된 이슈 그룹화, (5) 프로젝트 — 칸반 보드로 시각적 관리, (6) 연결된 풀 리퀘스트 — 이슈 해결을 위한 코드 변경사항 연결.

Q2: /resolve-issue 커맨드의 8단계 워크플로를 순서대로 나열하세요.

A: (1) 이슈 불러오기, (2) 브랜치 세팅, (3) 코드베이스 분석하기, (4) 이슈 해결 계획 세우기, (5) 이슈 해결하기, (6) 테스트 작성하기, (7) 검증하기 (테스트/린트/빌드), (8) 풀 리퀘스트 생성. 핵심은 "작업의 완료를 어떻게 확인하고 점검할 것인가?"를 설계하는 것이다.

Q3: 레이블의 복잡도(복잡, 보통, 쉬움)가 클로드 모델 선택과 어떻게 연관되는지 설명하세요.

A: 복잡도가 높은 이슈(복잡도:복잡)에는 성능이 높은 클로드 Opus를 사용하고, 복잡도가 낮은 이슈(복잡도:쉬움)에는 빠르고 비용 효율적인 클로드 Sonnet을 사용한다. 레이블로 복잡도를 표시해두면 여러 에이전트에게 작업을 분배할 때 적절한 모델을 선택하는 기준이 된다.

Q4: Git Worktree를 활용한 병렬 이슈 작업의 장점과 주의할 점은?

A: 장점 — 여러 이슈를 독립적인 워크트리에서 동시에 해결할 수 있어 작업 속도가 크게 향상되고, 진정한 의미의 개발 팀을 운영할 수 있다. 주의점 — 이슈가 너무 큰 단위로 나뉘면 충돌이 발생할 수 있으므로, 독립적으로 해결 가능한 작은 이슈 단위로 세분화하는 것이 핵심이다. 또한 머지 전에 코드와 프로젝트의 정합성을 반드시 확인해야 한다.

부록 A: 용어 사전

부록 B: 핵심 비교표

부록 C: 참고 자료 & 링크